docs: document dynamic sandbox secrets - #25785
Conversation
The sandbox credential guides only covered literal stored values and obsolete host-environment workflows. Document reference and command sources, refresh and verification controls, and provider-specific workflows for GitHub, 1Password, and AWS Secrets Manager. Co-authored-by: Codex <noreply@openai.com>
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
2 medium-severity style issues found in new content added to credentials.md. Both are introduced by this PR.
The initial workflow gave OP_ACCOUNT and AWS_PROFILE more prominence than their optional role warranted. Move provider selector support into a note and keep the primary 1Password and AWS flows focused on registering references. Co-authored-by: Codex <noreply@openai.com>
The refresh guidance conflated cache durations with on-demand resolution, and the provider-selection note described implementation rather than purpose. Separate the refresh modes, explain account and profile selection directly, and remove the semicolon flagged by review. Co-authored-by: Codex <noreply@openai.com>
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟢 APPROVE
The documentation for dynamic sandbox secrets (--ref and --command sources for sbx secret set) is well-written and follows Docker style conventions. No high or medium severity issues were found.
All four changed files (credentials.md, workflows.md, get-started.md, copilot.md) are hand-authored documentation — no vendored or generated content. The new content uses correct voice ("you"), avoids hedge words, and is appropriately scoped to the feature being introduced.
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
One documentation clarity issue found in the added content.
| --ref 'op://Work/Example/credential' | ||
| ``` | ||
|
|
||
| Dynamic custom secrets resolve on demand by default. Pass `--refresh` with a |
There was a problem hiding this comment.
[MEDIUM] Custom secrets default to on-demand resolution, but service secrets default to 55-minute caching — no explanation given
Line 331 (added by this PR) states "Dynamic custom secrets resolve on demand by default." However, line 141 (existing) states "Resolved service secrets are cached for 55 minutes by default." These are different commands (sbx secret set-custom vs sbx secret set), so the difference may be intentional, but the PR does not explain why the two commands behave differently. A reader comparing the two sections will likely see a contradiction and be uncertain which behavior applies in their case.
If the difference is intentional (a design choice for sbx secret set-custom), add a brief note explaining why, for example: "Custom secrets are resolved on every use because each host may require a fresh value." If the defaults should match, align the text.
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
The PR clearly documents dynamic secret sources (--ref and --command) for both service secrets and custom secrets, and is well-structured overall. Two medium findings warrant attention:
- The NOTE about OP_ACCOUNT/AWS_PROFILE doesn't clearly state whether the account/profile is persisted at registration or must be set in the daemon environment at resolution time — the current wording could mislead users.
- Custom secrets default to on-demand resolution while service secrets default to 55-minute caching. The asymmetry is factually correct but not cross-referenced, which could surprise users switching between the two secret types.
|
|
||
| > [!NOTE] | ||
| > To resolve a reference with a specific 1Password account or AWS profile, set | ||
| > `OP_ACCOUNT` or `AWS_PROFILE` when you run `sbx secret set`. `sbx` uses that |
There was a problem hiding this comment.
[MEDIUM] NOTE callout wording may confuse users about when OP_ACCOUNT/AWS_PROFILE must be set
The NOTE says to set OP_ACCOUNT or AWS_PROFILE "when you run sbx secret set", then adds that "sbx uses that account or profile whenever it resolves the secret." The second sentence implies the account/profile is persisted at registration — but it doesn't say that explicitly. Users could read the first sentence and conclude they only need the variable at registration time, and be confused if the daemon uses a different account at resolution time (e.g., if the variable isn't persisted and must be present in the daemon's environment too).
Consider clarifying the mechanism — for example: "The value is stored with the secret reference and used by the daemon at every resolution. You don't need to keep the variable set after registration."
| --ref 'op://Work/Example/credential' | ||
| ``` | ||
|
|
||
| Dynamic custom secrets resolve on demand by default. Pass `--refresh` with a |
There was a problem hiding this comment.
[MEDIUM] Custom secrets' on-demand default contrasts with service secrets' 55-minute cache default — asymmetry not called out
Service secrets cache for 55 minutes by default (documented a few sections above); custom secrets resolve on demand by default. Both defaults are correct in their own sections, but no cross-reference or explicit comparison is made. A user who reads only the custom secrets section won't know that the behavior differs from service secrets — they may be surprised by repeated slow lookups on every credential use, or assume the same 55-minute cache applies.
Consider adding a short note such as: "Unlike service secrets, which cache for 55 minutes by default, custom secrets resolve on demand on every use unless you pass --refresh <duration>."
Summary
Document the dynamic secret sources introduced for
sbx secret setandsbx secret set-customin docker/sandboxes#3946. Replace snapshot and host-environment credential workflows with native reference and command sources for GitHub, 1Password, and AWS Secrets Manager.The generated CLI reference remains on v0.38.0 and will update as part of the complete v0.39.0 release vendor sync.
@netlify /ai/sandboxes/security/credentials/
Preview:
Generated by Codex